插件设计

1. 简介

简道云开放平台以插件为载体，允许用户在多个功能场景中，通过可插拔的自定义代码逻辑，实现一些定制需求。插件可以被分发，插件的用户无需关注代码等技术细节。

创建插件后，系统会自动为您在插件内创建一个函数。一个插件可以包含一个或多个函数。每个函数主要包含3个属性: 代码、请求参数声明（以下简称入参声明)和返回参数声明（以下简称出参声明）。

通过请求参数声明定义插件使用者需要向您的函数传递哪些参数，通过返回参数声明定义您将为用户输出哪些结果，并最终编写代码来实现从参数到结果的转换或其他自定义逻辑。

1）插件设计页面及各部分功能见下表：

2）设计页面中的相关配置项，在前台使用插件时对应如下：

2. 新增函数

插件新建完成后，需要新增对应的函数。插件中的函数分为以下 2 种类型，在「插件设计」页面中，点击左下角的「新增函数」，您可根据自己的需求选择不同的函数进行创建：

3. 参数设计

插件有 4 种类型的参数可以配置，四者都非必须，按场景所需添加即可：

3.1 身份验证

1）身份验证是指用户在配置插件时需要填写应用的相关信息。插件设计过程中，您可选择「无」不验证身份，也可根据不同的集成模式进行身份验证，简道云中支持通过以下 6 种方式验证身份：

2）当选择身份验证方式为钉钉自建应用、企业微信应用、飞书自建应用和微信公众平台时，插件配置时需输入对应的应用 ID、应用 Key 和应用 Secret 进行身份验证。以选择钉钉自建应用为例，插件配置时效果如下所示：

3）当选择身份验证方式为 Basic Auth 时，插件配置时需输入对应的 Username 和 Password 进行身份验证。用户也可点击「添加参数」来设置更多身份验证选项，同时可在右侧属性栏中设置参数相关属性。

以授权参数仅为 Username 和 Password 为例，插件配置效果如下所示：

4）当选择身份验证方式为 OAuth2.0 - Client Credentials 时，验证方式支持设置以下内容：

以授权参数仅为 ClientID 和 ClientSecret 为例，插件配置效果如下所示：

3.2 通用参数

通用参数是使用插件时要配置的参数针对整个插件的参数。通常是在启用插件前，对插件进行的配置。

如，对接第三方平台需要配置的 API Key 等参数均可以在通用参数中设置。

3.3 请求参数

请求参数是在不同位置（比如前端事件/智能助手）中使用插件时，插件使用者需要提供的内容。比如：调用简道云部门接口时，需要使用者提供部门信息。

在设计请求参数时，可以选择不同类型的字段。不同的字段类型影响插件用户在配置插件时的输入方式，以及您在代码中获取到的值的类型。

举例，您在入参声明中添加了一个「部门选择」类型的参数，那么您的用户在配置插件时，将只能在界面上选择部门类型的值，或引用表单数据中支持转换为该类型的字段，比如「部门单选」/「部门多选」。

3.4 返回参数

返回参数是指插件执行完成后，返回给插件使用者的内容。插件使用者可以选择需要的内容回填至表单中，或传递给其他插件的其他函数。比如：调用部门接口后，将会返回部门下成员信息，可以将成员信息定义成返回参数。

2）参数类型可选择 any、object[]。

默认为 any，适用于请求参数与返回参数一对一的情况。

object[]，适用于请求参数与返回参数一对多的情况，返回信息为数组，比如通过部门查询部门下成员时，可能有多个成员。

若设置了参数类型为 object[]，则可通过点击列表头前的「+ 号」按钮，向下新增一行，作为子节点，如下所示。子节点的含义为数组内的具体元素，比如：返回多个成员，每个成员信息包含 成员昵称、成员编号等。

3）返回参数在前端事件插件中，配置效果如下所示：

3.5 表单校验提示信息

表单视图下配置通用参数、请求参数和返回参数时，支持对输入内容进行格式提示和实时校验，以降低输入错误的可能性，便于开发者校验修改表单配置，提高开发效率。效果如下图所示：

4. 代码编辑

参数设计确定后，您就需要为函数编写代码来实现其功能。

您的代码将被包裹于对应编程语言的一个函数之中，在代码中可以根据需要，通过 triggerConf 这一全局变量来获取定义的请求参数值，通过 return 关键字来返回最终的结果。

在编程语言选择处（上图 1）选择您熟悉的编程语言，在代码编辑器（上图 2）中编写函数代码。在您的代码中，可以引用您在入参声明中定义的参数，参数列表和值的类型可以参考右侧的（上图 3）中的提示。

4.1 后端函数-示例代码及说明

Python 3.6

# 可以引用一些第三方库.
import json
import requests

# 可以通过读取预定义的全局变量中的属性来获取您定义的参数.
# agentConf 含义是通用参数, 其结构为一个字典(dict), key 为您在入参模板中为控件定义的 ID, 值为用户指定的配置值.
# triggerConf 含义是请求参数, 其结构为一个字典(dict), key 为您在入参模板中为控件定义的 ID, 值为用户指定的配置值或表单字段的值.
api_key = str(agentConf.get('apiKey'))
dept_no = triggerConf.get('deptNo')

# 您需要对输入参数的类型, 格式做校验, 以增强函数逻辑的健壮性.
# 如下方对可能拿到的不同值格式进行处理，保证最终dept_no的准确性，具体值格式见本文「5.1 triggerConf (请求参数）结构」
try:
    if isinstance(dept_no, str):
        dept_no = json.loads(dept_no)
    if isinstance(dept_no, list):
        dept_no = dept_no[0] if 0 < len(dept_no) else None
    if isinstance(dept_no, dict):
        dept_no = dept_no.get('dept_no')
    if dept_no is None:
        dept_no = 1
    dept_no = int(dept_no)
except:
    raise ValueError('部门编号格式错误')

# 可以利用第三方库和请求参数, 在服务端环境中调用相关接口并获取结果.
url = ' https://api.jiandaoyun.com/api/v5/corp/department/user/list'
payload = {'dept_no': dept_no}
headers = {'Authorization': 'Bearer ' + api_key}
response = requests.post(url, json=payload, headers=headers)
if 300 <= response.status_code < 500:
    # 对特定结果主动抛错, 定义抛错文案.
    body = response.json()
    code = body.get('code', -1)
    message = body.get('message', '未知错误')
    message = '参数错误(%s): %s' % (code, message)
    raise ValueError(message)
# 对结果进行处理, 定义返回参数值.
# 您需要返回一个dict, dict的key和返回参数ID一一对应. 若返回为数组, 则对应出参需设置为object[]类型.
body = response.json()
users = [{'name': user.get('name'), 'username': user.get(
    'username')} for user in body.get('users', [])]
count = len(users)
return {
    "users": users,
    "count": count
}

# 可引用的全局变量, 支持的第三方库, 请求参数数据存储格式, 见本文「5.相关信息」.

Node.js 12

// 可以引用一些第三方库.
const _ = require('lodash');
const axios = require('axios');

// 可以通过读取预定义的全局变量中的属性来获取您定义的参数.
// agentConf 含义是通用参数, 其结构为一个对象(Object), key 为您在入参模板中为控件定义的 ID, 值为用户指定的配置值.
// triggerConf 含义是请求参数, 其结构为一个对象(Object), key 为您在入参模板中为控件定义的 ID, 值为用户指定的配置值或表单字段的值.
const apiKey = _.chain(agentConf).get(['apiKey']).trim().value();
let deptNo = _.get(triggerConf, ['deptNo']);

// 您需要对输入参数的类型, 格式做校验, 以增强函数逻辑的健壮性.
// 如下方对可能拿到的不同值格式进行处理，保证最终dept_no的准确性，具体值格式见本文「5.1 triggerConf (请求参数）结构」
try {
    if (_.isString(deptNo)) deptNo = JSON.parse(deptNo);
    if (_.isArray(deptNo)) deptNo = _.first(deptNo);
    if (_.has(deptNo, ['dept_no'])) deptNo = _.get(deptNo, ['dept_no']);
    deptNo = _.toInteger(deptNo);
} catch (e) {
    throw new Error('请输入正确的部门编号');
}

// 可以利用第三方库和请求参数, 在服务端环境中调用相关接口并获取结果.
try {
    const response = await axios({
        method: 'post',
        url: ' https://api.jiandaoyun.com/api/v5/corp/department/user/list',
        headers: {
            Authorization: `Bearer ${apiKey}`,
            'Content-Type': 'application/json'
        },
        data: { dept_no: deptNo }
    });
    const { data } = response;
    // 对结果进行处理, 定义返回参数值.
  	// 您需要返回一个object, object的key和返回参数ID一一对应. 若返回为数组, 则对应出参需设置为object[]类型.
    const users = _.chain(data)
    	.get(['users'])
    	.map((it) => ({ name: it.name, username: it.username }))
    	.value();
    return { users, count: users.length };
} catch (e) {
    // 对特定结果主动抛错, 定义抛错文案.
    const code =
        _.get(e, ['response', 'data', 'code']) || _.get(e, ['code']) || -1;
    let message =
        _.get(e, ['response', 'data', 'msg']) ||
        _.get(e, ['message']) ||
        '未知错误';
    message = `参数错误(${code}): ${message}`;
    throw new Error(message);
}

// 可引用的全局变量, 支持的第三方库, 请求参数数据存储格式, 见本文「6.相关信息」

4.2 前端扩展-示例代码及说明

// closeModal
const close = () => {
    $g.utils.closeModal();
    console.log('4s后模态框关闭');
};

const reportUrl = $g.env.baseUrl;

setTimeout(() => close(), 4000);

// GET
let response = await fetch(reportUrl, {method: 'GET'});
const resText = await response.text()
console.log(resText);

let message;

$g.ui.onmessage = function (msg) {
    message = msg
}

// openModal
// openModal：弹窗后继续代码执行，执行完结束 Worker。
// await openModal：弹窗后阻塞代码执行，按照开发者代码规定执行后续动作。
await $g.utils.openModal({
    title: '如果您对插件有任何需求，欢迎在本表单填写',
    url: reportUrl
});

// 调用后端函数
await $g.utils.callFunction({
    name: 'func.ID',
    data: {}
})

return {
    resText,
    message
}

4.3 参数提示的使用

代码编辑器右侧可展开参数提示，点击对应参数/函数，将添加对应调用语法到代码编辑器中。

4.4 参数校验提示信息

编写请求参数/返回参数/通用参数时，若出现代码错误，对应代码将用红色波浪线标注，且当鼠标放在对应代码上时，会显示详细的配置错误信息，便于开发者校验修改代码内容，提升编辑体验。效果如下所示：

4.5 语法错误提示信息

在前端扩展/后端函数的 Python 代码视图下，编辑器中支持在保存代码时提示语法错误。帮助开发者快速定位具体问题，为开发者提供更为直观、高效的开发体验。效果如下图所示：

5. 效果展示

1）后端函数插件配置及执行效果如下所示：

2）前端扩展插件配置及执行效果如下所示：

6. 相关信息

6.1 全局变量

您在代码中可以直接引用全局变量 triggerConf、agentConf、triggerContext。

agentConf (通用参数）结构

agentConf 即插件对应的通用参数。

其结构为对应编程语言的键值数据结构，如 Python 的 dict 或 Node.js 的 Object。在该结构中，键为您在入参声明中为变量指定的 ID，值为用户配置或引用的数据。

triggerConf (请求参数）结构

triggerConf 即插件函数对应的请求参数。

其结构为对应编程语言的键值数据结构，如 Python 的 dict 或 Node.js 的 Object。在该结构中，键为您在入参声明中为变量指定的 ID，值为用户配置或引用的数据(具体结构见下文)。

举例，您正在开发一个图像识别类的插件，并在该插件的请求参数中加入了一个文本字段用以接受用户的图片附件，那么基于不同的用户配置，您有可能得到不同的值:

您应该结合自己插件的功能和预期服务的用户场景，在代码中妥善处理上述情况，并在不计划支持该类型时通过抛出错误并附加消息向用户提示原因。

请求参数储值格式

1）保存自定义值

当用户在插件配置时直接保存「自定义值」时（如上图），请求参数中不同控件的储值格式如下表：

2）保存字段

当用户在简道云表单数据场景中使用插件时，可保存字段值(如上图)，入参声明中各个控件的储值格式如下表：

triggerContext 结构

triggerContext 中存储了运行环境的基本信息，如简道云的开放 API 域名等。

6.2 内置库支持列表

Node.js

Python

以下列表里包括可调用的内置库和第三方库。

6.3 可用前端扩展API

7. 注意事项

7.1 插件运行限制

插件在运行时有相应的限制。插件本身的超时时间为 60 s，但是不同使用场景本身也有自己的超时时间，比如前端事件的 20 s。

7.2 前端扩展调用后端函数

进行自建插件设计时，若在「前端扩展函数 >> 代码」处调用了后端函数，则插件执行时，前端扩展中的后端函数执行上限为 5 次。

以中奖通知为例，在表单内点击「新建邮件」便会打开编辑窗口，填写并点击「发送邮件」即可完成通知。其中，「新建邮件」为前端扩展，「发送邮件」为后端函数，则每次打开新建邮件弹窗后，发送邮件的上限为 5 次。